<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html><head><title>Programming in Lua : 24.2.3</title>
<link rel="stylesheet" type="text/css" href="pil.css">
</head>
<body>
<p class="warning">
<A HREF="contents.html"><IMG TITLE="Programming in Lua (first edition)" SRC="capa.jpg" ALT="" ALIGN="left"></A>This first edition was written for Lua 5.0. While still largely relevant for later versions, there are some differences.<BR>The third edition targets Lua 5.2 and is available at <A HREF="http://www.amazon.com/exec/obidos/ASIN/859037985X/theprogrammil3-20">Amazon</A> and other bookstores.<BR>By buying the book, you also help to <A HREF="../donations.html">support the Lua project</A>.
</p>
<table width="100%" class="nav">
<tr>
<td width="10%" align="left"><a href="24.2.2.html"><img border="0" src="left.png" alt="Previous"></a></td>
<td width="80%" align="center"><a href="contents.html"><font face="Helvetica,Arial,sanserif">
<font color="gray">Programming in </font><font color="blue"> Lua</font>
</font></a></td>
<td width="10%" align="right"><a href="24.3.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
<tr>
<td width="10%" align="left"></td>
<td width="80%" align="center"><a href="contents.html#P4">Part IV. The C API</a>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<a href="contents.html#24">Chapter 24. An Overview of the C API</a></td>
<td width="10%" align="right"></td></tr>
</table>
<hr/>
<p><h3>24.2.3 &ndash; Other Stack Operations</h3>

<p>Besides the above functions,
which interchange values between C and the stack,
the API offers also the following operations for generic stack manipulation:
<pre>
    int   lua_gettop (lua_State *L);
    void  lua_settop (lua_State *L, int index);
    void  lua_pushvalue (lua_State *L, int index);
    void  lua_remove (lua_State *L, int index);
    void  lua_insert (lua_State *L, int index);
    void  lua_replace (lua_State *L, int index);
</pre>
The <code>lua_gettop</code> function returns the number of elements in the stack,
which is also the index of the top element.
Notice that a negative index <code>-x</code> is equivalent to
the positive index <code>gettop - x + 1</code>.

<p><code>lua_settop</code> sets the top
(that is, the number of elements in the stack) to a specific value.
If the previous top was higher than the new one,
the top values are discarded.
Otherwise, the function pushes <B>nil</B>s on the stack to get the
given size.
As a particular case, <code>lua_settop(L, 0)</code> empties the stack.
You can also use negative indices with <code>lua_settop</code>;
that will set the top element to the given index.
Using this facility, the API offers the following macro,
which pops <code>n</code> elements from the stack:
<pre>
    #define lua_pop(L,n)  lua_settop(L, -(n)-1)
</pre>

<p>The <code>lua_pushvalue</code> function pushes
on the top of the stack a copy of the element at the given index;
<code>lua_remove</code> removes the element at the given index,
shifting down all elements on top of that position to fill in the gap;
<code>lua_insert</code> moves the top element into the given position,
shifting up all elements on top of that position to open space;
finally, <code>lua_replace</code> pops a value from the top and
sets it as the value of the given index,
without moving anything.
Notice that the following operations have no effect on
the stack:
<pre>
    lua_settop(L, -1);  /* set top to its current value */
    lua_insert(L, -1);  /* move top element to the top */
</pre>

<p>To illustrate the use of those functions,
here is a useful helper function that dumps
the entire content of the stack:
<pre>
    static void stackDump (lua_State *L) {
      int i;
      int top = lua_gettop(L);
      for (i = 1; i &lt;= top; i++) {  /* repeat for each level */
        int t = lua_type(L, i);
        switch (t) {
    
          case LUA_TSTRING:  /* strings */
            printf("`%s'", lua_tostring(L, i));
            break;
    
          case LUA_TBOOLEAN:  /* booleans */
            printf(lua_toboolean(L, i) ? "true" : "false");
            break;
    
          case LUA_TNUMBER:  /* numbers */
            printf("%g", lua_tonumber(L, i));
            break;
    
          default:  /* other values */
            printf("%s", lua_typename(L, t));
            break;
    
        }
        printf("  ");  /* put a separator */
      }
      printf("\n");  /* end the listing */
    }
</pre>
This function traverses the stack from bottom to top,
printing each element according to its type.
It prints strings between quotes; for numbers it uses a `<code>%g</code>&acute; format;
for other values (tables, functions, etc.) it prints only their types
(<code>lua_typename</code> converts a type code to a type name).

<p>The following program uses <code>stackDump</code> to further
illustrate the manipulation of the API stack:
<pre>
    #include &lt;stdio.h>
    #include &lt;lua.h>
    
    static void stackDump (lua_State *L) {
      ...
    }
    
    int main (void) {
      lua_State *L = lua_open();
      lua_pushboolean(L, 1); lua_pushnumber(L, 10);
      lua_pushnil(L); lua_pushstring(L, "hello");
      stackDump(L);
                       /* true  10  nil  `hello'  */
    
      lua_pushvalue(L, -4); stackDump(L);
                       /* true  10  nil  `hello'  true  */
    
      lua_replace(L, 3); stackDump(L);
                       /* true  10  true  `hello'  */
    
      lua_settop(L, 6); stackDump(L);
                       /* true  10  true  `hello'  nil  nil  */
    
      lua_remove(L, -3); stackDump(L);
                       /* true  10  true  nil  nil  */
    
      lua_settop(L, -5); stackDump(L);
                       /* true  */
    
      lua_close(L);
      return 0;
    }
</pre>

<hr/>
<table width="100%" class="nav">
<tr valign="top">
<td width="90%" align="left">
<small>
  Copyright &copy; 2003&ndash;2004 Roberto Ierusalimschy.  All rights reserved.
</small>
</td>
<td width="10%" align="right"><a href="24.3.html"><img border="0" src="right.png" alt="Next"></a></td>
</tr>
</table>


</body></html>

